Common Models

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

Matching is accent insensitive in all databases. Pérez will match Perez and vice versa. Matching is also 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",
  "suffix": "M.D.",
  "title": "Dr.",
  "salutation": "Dr. Gordon",
  "envelopeName": "Dr. Jim Gordon",
  "pronouns": {
    "pronounId": 3
  },
  "contactMethodPreferenceCode": "S",
  "nickname": "Jim",
  "website": "www.jimgordon.com",
  "party": "D",
  "employer": "Acme Medical Group",
  "occupation": "Physician",
  "jobTitle": "Doctor of Internal Medicine",
  "sex": "M",
  "dateOfBirth": "1976-07-04",
  "yearOfBirth": 1976,
  "collectionLocationId": 123,
  "electionType": "G",
  "cycle": "2020",
  "selfReportedRaces": [
    {
      "reportedRaceId": 4
    }
  ],
  "selfReportedEthnicities": [
    {
      "reportedEthnicityId": 5
    }
  ],
  "selfReportedLanguagePreference": {
    "reportedLanguagePreferenceId": 6
  },
  "selfReportedSexualOrientations": [
    {
      "reportedSexualOrientationId": 1
    }
  ],
  "selfReportedGenders": [
    {
      "reportedGenderId": 1
    }
  ],
  "emails": [
    {
      "email": "[email protected]",
      "type": "P",
      "isPreferred": true,
      "isSubscribed": null,
      "subscriptionStatus": "N"
    },
    {
      "email": "[email protected]",
      "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
    }
  ],
  "identifiers": [
    {
      "type": "bsdid",
      "externalId": "746313"
    }
  ],
  "customFieldValues": [
    {
      "customFieldId": 500,
      "customFieldGroupId": 100,
      "assignedValue": "someValue"
    }
  ],
  "contactMode": "Person"
}

Match Candidate

Property

Type

Max length

Description

vanId

string

n/a

Optional; unique identifier of the My Campaign or My Voters record if known in advance

firstName

string

75

Optional; a person’s first name

middleName

string

75

Optional; a person’s middle name

lastName

string

150

Optional; a person’s last name

suffix

string

50

Optional; part of name following last name, e.g. "Jr."

title

string

10

Optional; an honorific

salutation

string

100

Optional; preferred greeting for correspondence

envelopeName

string

350

Optional; preferred name to use for mailings

pronouns

object

n/a

Optional; a person's pronouns

nickname

string

50

Optional; a person's preferred informal name

website

string

50

Optional; a person's personal website

party

string

1

Optional; a one-character string indicating party affiliation, e.g. "D"

contactMethodPreferenceCode

string

1

Optional; a person's preferred method of contact; must be one of: P → phone, E → email, M → mail, F → fax, or S → SMS

employer

string

50

Optional; name of the organization where the person works, e.g. "Kennedy High School"; may not be available in every context

occupation

string

50

Optional; nature of the person’s work, e.g. "teacher"; may not be available in every context

jobTitle

string

150

Optional; name of the position the person holds at an organization; maybe not be available in every context

sex

string

1

Optional; a one-character string indicating sex; must be M or F

dateOfBirth

datetime

n/a

Optional; a person’s date of birth; must be ISO 8601 formatted and in the 20th or 21st century

yearOfBirth

int

4

Optional; the year a person was born

collectedLocationId

int

n/a

Optional; location where a person's voter registration application was collected

electionType

string

2

Optional; type of election registered for; must be one of G → General, P → Primary, R → Run-off, PP → Presidential Primary, SP → Special Primary, SG → Special General, MP → Municipal Primary, MG → Municipal General, C → Caucus, or O → Other

cycle

string

4

Optional; a numeric string indicating the election year a person registered to vote

selfReportedRaces

array

n/a

Optional; the person’s race(s); reportedRaceId must match one of the reported races available in the current context

selfReportedEthnicities

array

n/a

Optional; a person’s ethnicity or ethnicities; reportedEthnicityId must match one of the reported ethnicities available in the current context

selfReportedGenders

array

n/a

Optional; a person’s gender(s); reportedGenderId must match one of the reported genders available in the current context

selfReportedSexualOrientations

array

n/a

Optional; a person’s sexual orientation(s); reportedSexualOrientationId must match one of the reported sexual orientation available in the current context

selfReportedLanguagePreference

object

n/a

Optional; a person’s language preference: reportedLanguagePreferenceId must match one of the reported language preferences available in the current context

emails

array

n/a

Optional; an array of email objects

phones

array

n/a

Optional; an array of phone objects

addresses

array

n/a

Optional; an array of address objects

identifiers

array

n/a

Optional; an array of identifier objects

customFieldValues

array

n/a

Optional; an array of customFieldValue objects

organizationContactCommonName

string

150

Optional; an organization's common name; applicable only in My Campaign databases where organizations as contacts is enabled

organizationContactOfficialName

string

150

Optional; an organization's official name; applicable only in My Campaign databases where organizations as contacts is enabled

contactMode

string

n/a

Optional; the type of contact; must be Person or Organization; applicable only in My Campaign databases where organizations as contacts is enabled

🚧

Note:

Many of the properties listed above are expressed as arrays (e.g., addresses, phones, emails, etc.). If objects (rather than an array of a single object) are passed, they will be ignored.

Email

Property

Type

Description

email

string

Required; a valid email address

type

string

Optional; one of: P → personal, W → work, O → other. Default, if not supplied, is P.

isPreferred

bool

Optional; an indicator of whether the email address is the person’s preferred address; defaults to false

isSubscribed

bool

Deprecated if Targeted Email is available. Optional; indicates whether the email address may be used in a broadcast email. Default value is true. If it’s explicitly set to false, it is treated as an opt-out and you will not be able to resubscribe the email address.

subscriptionStatus

string

Optional; indicates the email address subscription status for Targeted Email. One of U → unsubscribed, N → neutral, S→ subscribed. If unspecified, assumed value is S. Only email addresses with status S will receive messages from Targeted Email. Once an email address has been unsubscribed, it may not be subscribed or set to neutral. This property is only available if Targeted Email is available; it is not valid to set this property and isSubscribed at the same time.

Phone

Property

Type

Description

phoneId

int

Read-only; unique identifier of the phone.

phoneNumber

string

Required; after removing all non-numeric characters, the number is evaluated using country specific validation, defaulting to the target context’s country if no other is provided.

phoneType

string

Optional; one of: H → home, W → work, C → cell (alias for mobile), M → main, 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

phoneOptInStatus

string

Optional; one of: I → opt in, U → unknown, O → opt out. Default, if not supplied, is U

isCellStatus

object

Optional; indicates the level of confidence for whether the phone number is a cell phone. See GET /phones/isCellStatuses for more information. Specifying just a valid value for either the statusId property or the statusName, instead of both, would still work. If no value is provided, any existing explicitly applied isCellStatus for this number will remain unchanged.

dialingPrefix

string

Optional; 1 to 3 numeric characters that indicate the country associated with the phone number. If this and countryCode are both specified, they must refer to the same country.

countryCode

string

Optional; the ISO alpha-2 code for the country associated with the phone number. If this and dialingPrefix are both specified, they must refer to the same country.

Address

Property

Type

Description

addressId

int

Read-only; unique identifier of the address on this person

addressLine1

string

Optional; indicates first line of a street address when used in the POST /people/findOrCreate. In the GET method, indicates the result of concatenating all three address lines and standardizing the resulting 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: Mailing, Home, Voting, Work, Custom; some types may not be available in certain contexts. Note that Home and Voting have identical meaning. If a mailing address has not been provided for a contact, then the home address for that contact will also be used as the contact’s mailing address.

isPreferred

bool

Read-only; indicates whether this address is the best known address of the indicated type. The best known address is the most recently-updated address of a given address type.

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.

Property

Type

Description

type

string

Required; a known external identifier that is available in the current context. Use votervanid for VoterFile VANID if making a MyCampaign call. Use dwid for Catalist DWIDs in either VoterFile or MyCampaign mode.

externalId

string

Required; case-insensitive

Custom Field Value

Property

Type

Description

customFieldId

int

Required; a known custom field identifier that is available in the current context.

customFieldGroupId

int

Required; a known custom field group identifier that identifies the Custom Field Group to which this Custom Field belongs, and that is available in the current context.

assignedValue

string

The value to be applied to the Custom Field. The value must be consistent with the type of the Custom Field

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.

Status

HTTP Code

Description

Matched

302 Found

A match was found (and updated, if relevant) and the Location header 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 Location header is set)

Processed

204 No Content

Not implemented

UnmatchedProcessed

204 No Content

Not implemented

Person

Most GET endpoints return a full Person response object.

Property

Type

Description

vanId

int

Unique identifier of the My Campaign or My Voters record

firstName

string

A person’s first name

middleName

string

A person's middle name

lastName

string

A person's last name

suffix

string

Part of name following last name, e.g. "Jr."

title

string

An honorific

sourceFileTitle

string

Honorific provided in the source file (most often a voter file)

sourceFileFirstName

string

First name provided in the source file (most often a voter file)

sourceFileMiddleName

string

Middle Name provided in the source file (most often a voter file)

sourceFileLastName

string

Last Name provided in the source file (most often a voter file)

sourceFileSuffix

string

Suffix provided in the source file (most often a voter file)

contactMode

string

The type of contact; one of Person or Organization; applicable only in My Campaign databases where organizations as contacts is enabled

organizationContactCommonName

string

An organization's common name; applicable only in My Campaign databases where organizations as contacts is enabled

organizationContactOfficialName

string

An organization's official name; applicable only in My Campaign databases where organizations as contacts is enabled

salutation

string

Preferred greeting for correspondence; defaults to a person's firstName

formalSalutation

string

Preferred formal greeting for correspondence; defaults to title and lastName for people or "Friends" for organizations

additionalSalutation

string

Additional preferred greeting for correspondence; defaults to organizationContactCommonName for organizations

pronouns

object

A person's pronouns

envelopeName

string

Preferred name to use for mailings; defaults to the person's full name, including their middle initial, or organizationContactCommonName depending on the contact type

formalEnvelopeName

string

Preferred formal name to use for mailings; defaults to the person's full name, including their middle initial, title, and suffix, or organizationContactOfficialName depending on the contact type

additionalEnvelopeName

string

Additional preferred name to use for mailings

contactMethodPreferenceCode

string

A person's preferred method of contact; must be one of: P → phone, E → email, M → mail, F → fax, or S → SMS

nickname

string

A person's preferred informal name

website

string

A person's personal website

professionalSuffix

string

A person's professional suffix, e.g. "M.D."

party

string

A one-character string indicating party affiliation, e.g. “D”

employer

string

Name of the organization where the person works, e.g. "Kennedy High School"; may not be available in every context

occupation

string

Nature of the person’s work, e.g. "teacher"; may not be available in every context

jobTitle

string

Name of the position the person holds at an organization; maybe not be available in every context

sex

string

A one-character string indicating sex

dateOfBirth

datetime

A person’s ISO 8601 formatted date of birth

selfReportedRaces

array

A person’s reported race(s)

selfReportedEthnicities

array

A person’s reported ethnicity or ethnicities

selfReportedGenders

array

A person’s reported gender(s)

selfReportedSexualOrientations

*array

A person’s reported sexual orientation(s)

selfReportedLanguagePreference

object

A person’s reported language preference

emails

array

An array of email objects associated with a contact

phones

array

An array of phone objects associated with a contact

addresses

array

An array of address objects associated with a contact; will contain only the best Home address and best Mailing address, if available

recordedAddresses

array

An array of address objects; will contain all known addresses associated with a contact

identifiers

array

An array of all known external identifiers associated with a contact

codes

array

An array of codes associated with a contact

customFields

array

An array of (custom fields)[ref:custom-fields] associated with a contact

primaryCustomField

object

The primary (custom field)[ref:custom-fields] associated with a contact

contributionSummary

object

A summary of a person's contribution activity

suppressions

array

An array of suppressions associated with a contact

caseworkCases

array

An array of casework cases associated with a contact

caseworkIssues

array

An array of casework issues associated with a contact

caseworkStories

array

An array of casework stories associated with a contact

notes

array

An array of notes associated with a contact

scores

array

An array of scores associated with a contact

customProperties

array

An array of custom properties associated with a contact

electionRecords

array

An array of election records associated with a contact

membershipStatus

object

A person's membership status

organizationRoles

array

An array of roles associated with an organization

districts

array

An array of districts associated with a contact

disclosureFieldValues

array

An array of disclosure field values associated with a contact

surveyQuestionResponses

array

An array of (survey question responses)[ref:survey-questions] associated with a contact

finderNumber

string

The finder number associated with a contact

biographyImageUrl

string

The url for a contact's biography image

primaryContact

object

The primary contact at an organization

pledgesSummaryDesignations

array

A summary of a person's pledge activity

Suppression

Property

Type

Description

suppressionCode

string

Short code which identifies the suppression, e.g. "NC"

suppressionName

string

Full explanation of the suppression, e.g. "Do not call"

Disclosure Field Value

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

Property

Type

Description

disclosureFieldId

int

Identifies the Disclosure Field. Together, the designation id and disclosure field id provide a unique identifier of a Disclosure Field.

disclosureFieldValue

string

The value of the Disclosure Field

designationId

int

The unique identifier of the (Designation)[ref:designations] of the Disclosure Field